Crate jsonptr

jsonptr - JSON Pointers for Rust

Data structures and logic for resolving, assigning, and deleting by JSON Pointers (RFC 6901).

Usage

JSON Pointers can be created either with a slice of strings or directly from a properly encoded string representing a JSON Pointer.

Resolve values

Pointer::resolve

use jsonptr::Pointer;
use serde_json::json;

let mut data = json!({"foo": { "bar": "baz" }});
let ptr = Pointer::new(["foo", "bar"]);
let bar = ptr.resolve(&data).unwrap();
assert_eq!(bar, "baz");

Resolve::resolve

use jsonptr::{Pointer, Resolve};
use serde_json::json;

let mut data = json!({ "foo": { "bar": "baz" }});
let ptr = Pointer::new(["foo", "bar"]);
let bar = data.resolve(&ptr).unwrap();
assert_eq!(bar, "baz");

ResolveMut::resolve_mut

use jsonptr::{Pointer, ResolveMut};
use serde_json::json;

let ptr = Pointer::try_from("/foo/bar").unwrap();
let mut data = json!({ "foo": { "bar": "baz" }});
let mut bar = data.resolve_mut(&ptr).unwrap();
assert_eq!(bar, "baz");

Assign

Pointer::assign

use jsonptr::Pointer;
use serde_json::json;

let ptr = Pointer::try_from("/foo/bar").unwrap();
let mut data = json!({});
let _previous = ptr.assign(&mut data, "qux").unwrap();
assert_eq!(data, json!({ "foo": { "bar": "qux" }}))

Assign::asign

use jsonptr::{Assign, Pointer};
use serde_json::json;

let ptr = Pointer::try_from("/foo/bar").unwrap();
let mut data = json!({});
let _previous = data.assign(&ptr, "qux").unwrap();
assert_eq!(data, json!({ "foo": { "bar": "qux" }}))

Delete

Pointer::delete

use jsonptr::Pointer;
use serde_json::json;

let mut data = json!({ "foo": { "bar": { "baz": "qux" } } });
let ptr = Pointer::new(&["foo", "bar", "baz"]);
assert_eq!(ptr.delete(&mut data), Some("qux".into()));
assert_eq!(data, json!({ "foo": { "bar": {} } }));

// unresolved pointers return None
let mut data = json!({});
assert_eq!(ptr.delete(&mut data), None);

Delete::delete

use jsonptr::{Pointer, Delete};
use serde_json::json;

let mut data = json!({ "foo": { "bar": { "baz": "qux" } } });
let ptr = Pointer::new(["foo", "bar", "baz"]);
assert_eq!(ptr.delete(&mut data), Some("qux".into()));
assert_eq!(data, json!({ "foo": { "bar": {} } }));

// replacing a root pointer replaces data with `Value::Null`
let ptr = Pointer::default();
let deleted = json!({ "foo": { "bar": {} } });
assert_eq!(data.delete(&ptr), Some(deleted));
assert!(data.is_null());

Feature Flags

Flag	Enables
"std"	implements std::error::Error for errors
"url"	TryFrom<url::Url> for Pointer
"uniresid"	TryFrom<uniresid::Uri> + TryFrom<uniresid::AbsoluteUri> for Pointer
"fluent-uri"	TryFrom<fluent_uri::Uri<&str>> + TryFrom<fluent_uri::Uri<String>> + TryFrom<fluent_uri::Uri<&mut [u8]>> for Pointer

Contributions / Issues

Contributions and feedback are always welcome and appreciated.

If you find an issue, please open a ticket or a pull request.

License

MIT or Apache 2.0.

Modules

• prelude
  Exposes the traits Assign, Delete, Resolve, ResolveMut

Structs

• Assignment
  The data structure returned from a successful call to assign.
• NotFoundError
  NotFoundError indicates that a Pointer was not found in the data.
• NotUtf8Error
  Pointer was not in UTF-8 format.
• OutOfBoundsError
  Indicates that the Pointer contains an index of an array that is out of bounds.
• ParseError
  ParseError represents an that an error occurred when parsing an index.
• Pointer
  A JSON Pointer is a string containing a sequence of zero or more reference tokens, each prefixed by a ‘/’ character.
• ReplaceTokenError
  Returned from Pointer::replace_token when the provided index is out of bounds.
• Token
  A Token is a segment of a JSON Pointer, seperated by ‘/’ (%x2F). It can represent a key in a JSON object or an index in a JSON array.
• Tokens
  An iterator over the tokens in a Pointer.
• UnresolvableError
  Represents an error that occurs when attempting to resolve a Pointer that encounters a leaf node (i.e. a scalar / null value) which is not the root of the Pointer.

Enums

• Error
  An enum representing possible errors that can occur when resolving or mutating by a JSON Pointer.
• IndexError
  Indicates an error occurred while parsing a usize (ParseError) or the parsed value was out of bounds for the targeted array.
• MalformedPointerError
  Indicates that a Pointer was malformed.
• MaybePointer
  Helper type for deserialization. Either a valid Pointer or a string and the parsing error

Traits

• Assign
  Assign is implemented by types which can internally assign a serde_json::Value by a JSON Pointer.
• Delete
  Delete is implemented by types which can internally remove a value based on a JSON Pointer
• Resolve
  Resolve is implemented by types which can resolve a reference to a serde_json::Value from the path in a JSON Pointer.
• ResolveMut
  ResolveMut is implemented by types which can resolve a mutable reference to a serde_json::Value from the path in a JSON Pointer.